ManualInstallation
Prev: ManualRequirements --- Up: UserManual --- Next: ManualApacheConfig ---- = GENERAL INSTALLATION = 1. Unpack 2. Run the configure script From within the temporary directory you just created, run the "configure" script. You'll want to read this entire section, and decide on the option switches which you will want to specify to configure, before you actually run it. Having multiple console windows available during (this or any other) install is exceptionally helpful. To see a list of configuration options, use the "help" flag, which will show you a list of options: ./configure --help We've also listed the options here. Defaults are specified in brackets. Configuration: -h, --help display this help and exit --help=short display options specific to this package --help=recursive display the short help of all the included packages -V, --version display version information and exit -q, --quiet, --silent do not print `checking...' messages --cache-file=FILE cache test results in FILE disabled -C, --config-cache alias for `--cache-file=config.cache' -n, --no-create do not create output files --srcdir=DIR find the sources in DIR dir or `..' Installation directory By default, `make install' will install all the files in `/opt/rt3/bin', `/opt/rt3/lib' etc. You can specify an installation prefix other than `/opt/rt3' using `--prefix', for instance `--prefix=$HOME'. --prefix=PREFIX install architecture-independent files in PREFIX /opt/rt3 --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX PREFIX Installation directory fine-tuning Here are some more configure switches you can use to fine tune exactly where the install process should put its files. If you don't know why or to where you might change these, just accept the default. --bindir=DIR user executables EPREFIX/bin --sbindir=DIR system admin executables EPREFIX/sbin --libexecdir=DIR program executables EPREFIX/libexec --datadir=DIR read-only architecture-independent data PREFIX/share --sysconfdir=DIR read-only single-machine data PREFIX/etc --sharedstatedir=DIR modifiable architecture-independent data PREFIX/com --localstatedir=DIR modifiable single-machine data PREFIX/var --libdir=DIR object code libraries EPREFIX/lib --includedir=DIR C header files PREFIX/include --oldincludedir=DIR C header files for non-gcc /usr/include --infodir=DIR info documentation PREFIX/info --mandir=DIR man documentation PREFIX/man Optional Features: --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE=ARG include FEATURE ARG=yes --enable-layout=LAYOUT Use a specific directory layout (Default: RT3) Optional Packages: --with-PACKAGE=ARG use PACKAGE ARG=yes --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) --with-rt-group=GROUP group to own all files (default: rt) --with-bin-owner=OWNER user that will own rt executable files (default root) --with-libs-owner=OWNER user that will own RT libraries (default root) --with-libs-group=GROUP group that will own rt binaries (default bin) --with-db-type=TYPE sort of database RT will use (default: mysql; others are Oracle, Informix, Pg, SQLite) --with-db-host=HOSTNAME FQDN of database server (default: localhost) --with-db-port=PORT port on which the database listens on --with-db-rt-host=HOSTNAME FQDN of database server (default: localhost) --with-db-dba=DBA name of database administrator (default: root) --with-db-database=DBNAME name of the database to use (default: rt3) --with-db-rt-user=DBUSER name of database user (default: rt_user) --with-db-rt-pass=PASSWORD password for database user (default: rt_pass) --with-web-user=USER user the web server runs as (default: www) --with-web-group=GROUP group the web server runs as (default: www) --disable-option-checking ignore unrecognized --enable/--with options --disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no) --enable-FEATURE=ARG include FEATURE ARG=yes --enable-layout=LAYOUT Use a specific directory layout (Default: relative) --enable-devel-mode Turn on development aids that might hurt you in production --enable-graphviz Turns on support for RT's GraphViz dependency charts --enable-gd Turns on support for RT's GD pie and bar charts --enable-gpg Turns on GNU Privacy Guard (GPG) support Some influential environment variables: PERL Perl interpreter command Use these variables to override the choices made by 'configure' or to help it to find libraries and programs with unusual names/locations. Look at all the available flags and determine your RT install preferences, then ./configure (with the flags you want) You might find it useful to put all your switches into a script in your build directory called build, so that if you need to run it more than once, or refer back to it, it's been saved somewhere. You can then do your build by merely typing ./build 3. Dependencies After you build RT, but before you can run it, you must satisfy RT's myriad dependencies. RT makes use of many components external to the distributed package, and these must all be installed before the package will run. You must always do this step on install/update or upgrade actions. First of all, check for compliance, using the CPAN-based dependency checker (if you have never run CPAN on this machine as this user, see below to manually initialize it first, or else :-): make testdeps or (the long way) perl sbin/rt-test-dependencies --with- --with- Instead of , type either mysql, postgres or oracle. Instead of , type either fastcgi, modperl1, or modperl2. If there are unsatisfied dependencies (that is, if you are missing stuff), you will see complaints like "such-and-such not installed". Look carefully; these don't stand out that much. Go, ye, and fix dependencies. As root: make fixdeps or perl sbin/rt-test-dependencies \ --with- --with- --install NOTE: If you have having difficulties with 'make fixdeps' due to errors like: > Couldn't mkdir '/root/.cpan/build/tmp': File exists < Set the following environment variable to tell fixdeps to invoke CPAN as a command line tool: RT_FIX_DEPS_CMD='/usr/bin/perl -MCPAN -e"install %s"' Make sure to export this variable with export RT_FIX_DEPS_CMD NOTE: if you've never run CPAN on your machine as the user whom you are building RT as, run it first or this part of the install will not be fun. perl -MCPAN -e shell You'll be walked through the configuration process. When you're done: quit NOTE: if things are still messed up, you are logged in as root, right? Alternately, you could install missing items by hand. For example: perl -MCPAN -e 'install DBD::mysql' would install DBD::mysql. NOTE: Some modules may require environment variables defined, for example Apache::Request. NOTE: If you are using FastCGI, you will need to make sure that the FCGI module is installed. If not, run perl -MCPAN -e 'install FCGI' or something equivalent. Re-check to make sure everything was installed properly: make testdeps or perl sbin/rt-test-dependencies --with- --with- NOTE: Some versions of the MIME::Tools package will not install cleanly. Specifically, MIME::Tools version 5.427 is missing a dependency that will not be installed automatically by the CPAN shell. It requires MIME::Base64 to be installed first. Otherwise, MIME::Entity will fail during testing and terminate the installation. Install MIME::Base64 explicitly, either manually or using: # perl -MCPAN -e "install 'MIME::Base64'" Thereafter, installing dependencies worked without further problems for me. - Ed Eaglehouse NOTE: graphviz dependencies can be met with packages from here: http://www.graphviz.org/Download..php. On CentOS 5.4, adding the repository provided by graphviz.org and doing yum install graphviz graphviz-gd graphviz-devel cleared up all related requirements. Installing additional packages via yum install gd gd-devel and yum install expat expat-devel resolved all dependency problems. Doing 'make fixdeps' after a configure stage such as ./configure --with-web-handler=modperl2 --enable-graphviz --enable-gd --enable-gpg completed with all dependencies met. 4. rt group Create a new Unix group called 'rt' (or whatever you gave to the --with-rt-group option to the configure script). 5. For new installations only If you're upgrading within the RT 3.x series, skip to step 6: 5.1 Init DB As root and from within the rt build directory, type: make install Now you need to modify the installed [=etc/RT_SiteConfig.pm] to specify the connections to your DBMS engine and then type: make initialize-database For some database backends (MySQL at least) it is not able to create the database user. So you have to create that user beforehand and you have to give it rights for the database. For MySQL with the default =$DatabaseUser, =$DatabaseName and =$DatabasePassword, do this SQL command (as root database user): GRANT ALL PRIVILEGES ON rt3.* TO 'rt_user'@'localhost' IDENTIFIED BY 'rt_pass' Replace the values 'rt3', 'rt_user', 'localhost' and 'rt_pass' by whatever is appropriate for you. 5.2 Drop DB if something goes wrong If the make fails, type: make dropdb fix whatever's broken, and start over from step "init DB" step 5.3 if still failing... If make install still fails, look in /etc/httpd/httpd.conf or /etc/httpd/conf/commonhttpd.conf (or wherever your httpd.conf is; this may vary by Unix distribution; locate httpd.conf may help) for a line that reads "Group " and another that reads "User " Go to your RT source directory and type (without the brackets, substituting the right Group and User from the file you just looked at): ./configure --with-web-group= --with-web-user= Skip to step 7. 5.4 initdb fails The defaults were changed in PostgreSQL 8.1 and now tables are created without OIDs. One of workarounds is to add the following block at the top of etc/schema.Pg file: -- -- Enforce OID creation for 8.1+ -- set default_with_oids = 't'; Once it's done "make initialize-database" will work perfectly. -- Added by GalaxyMaster 6. For an Upgrade For upgrading within the RT 3.x series - if you are not upgrading or have already completed step 5, skip to step 7. As root, type: make upgrade (replace "make" with the local name for Make, if you need to) This will build new executable files, config files and libraries without overwriting your RT database. It may then instruct you to update your RT system database objects 7. Configuration Edit [=etc/RT_SiteConfig.pm] in your RT installation directory, by specifying any values you need to change from the defaults as defined in RT_Config.pm. It is easiest to do this by copying RT_Config.pm to RT_SiteConfig.pm, and then uncommenting and changing anything you need to set, though perhaps this isn't quite the best approach. In many cases sensible defaults have been included. In others, you must supply a value. Some values (such as the RT log directory) will come from values you supplied in the Makefile. You'll find further explanation inline in the RT_SiteConfig.pm file. You should look at and consider changing the following entries: $DatabasePassword = 'rt_pass' which is the password the DatabaseUser should use to access the database. NOTE: Some MySQL users have had trouble with passwords of longer than 8 characters; if you cannot connect, try a password of 8 characters or fewer. $CanonicalizeEmailAddressMatch = 'subdomain.example.com$'; $CanonicalizeEmailAddressReplace = 'example.com'; The $CanonicalizeEmailAddress variables allow you to keep incoming messages consistent, such as when a site removes the subdomain from an email address. In the example presented by the defaults, if messages from your organization sometimes come from exchange.example.com and sometimes from example.com, you'd set $CanonicalizeEmailAddressMatch to exchange.example.com and $CanonicalizeEmailAddressReplace to example.com $SenderMustExistInExternalDatabase = undef; If $SenderMustExistInExternalDatabase is true, RT will refuse to auto-create non-staff accounts for unknown users filing new tickets by email if you are using the "LookupSenderInExternalDatabase" option elsewhere in RT_SiteConfig.pm. Instead, an error message will be returned and RT will forward the user's message to $RTOwner as defined in RT_SiteConfig.pm. If you are not using $LookupSenderInExternalDatabase, this option has no effect. If you define an AutoRejectRequest template, RT will use this template for the rejection message. $CorrespondAddress = 'RT::CorrespondAddress.not.set'; $CommentAddress = 'RT::CommentAddress.not.set'; $CorrespondAddress and $CommentAddress are the default addresses that will be listed in both From: and Reply-To: headers of reply and comment mail, respectively, sent by RT, unless they are overridden by a queue-specific address. $MailCommand = 'sendmailpipe'; $MailCommand defines which method RT will use to try to send mail. We know sendmailpipe works fairly well. If sendmailpipe doesn't work well for you, try sendmail. Note that you should remove the '-t' from $SendmailArguments if you use sendmail rather than sendmailpipe. Also note that sendmailpipe and sendmail aren't the names of commands on your system, but instructions that tell RT what mail delivery subsystem to try. *Don't forget to restart the Apache webserver after doing changes in RT_SiteConfig.pm!* This is true of any change, but we mention it here since this is the configuration option you're most likely to have to experiment with. $SendmailArguments = "-oi -t"; $SendmailArguments defines what flags to pass to $Sendmail, assuming you picked sendmail or sendmailpipe as the $MailCommand. If you picked sendmailpipe, then $SendmailArguments must include the "-t" flag. The default options are good for most sendmail wrappers and workalikes. $SendmailPath = "/usr/sbin/sendmail"; If you selected sendmailpipe as $MailCommand, you must specify the path to your sendmail executable file in $SendmailPath. If you did not select sendmailpipe this has no effect. In case of Exim, the following configuration works: Set($MailCommand , 'sendmail'); Set($SendmailArguments , "-bm -- "); Set($SendmailPath, "/usr/sbin/exim4"); Set($NotifyActor, 1); $Timezone = 'US/Eastern'; $Timezone is used to convert times entered by users into GMT and back again. It should be set to a timezone recognized by your local Unix box, and -- in general -- you should pick the timezone the majority of your users reside in. $UseFriendlyToLine = 0; RT can set a "friendly", rather than blank, To: header when sending messages to Ccs or AdminCcs. This feature does not work with Sendmail™-brand sendmail. If you are using sendmail, rather than postfix, qmail, exim, or some other program, you must disable this option (by setting it to 0 rather than 1). $WebPath = ""; A variable used to help RT construct URLs that point back to RT. If you've put RT somewhere other than at the root of your webserver, you need to define a WebPath. RT uses this in the construction of relative URLs. $WebPath requires a leading / but no trailing / Example: if your installation is at http://www.fsck.com/rt/ set this to "/rt". $WebBaseURL = "http://not.configured:80"; A variable used to help RT construct URLs that point back to RT. $WebBaseURL is the base of the URL. it should usually include the scheme, the host, and the port if non-standard. Example: "https://fsck.com" or "http://fsck.com:88" $WebBaseURL doesn't need a trailing / $WebURL = $WebBaseURL . $WebPath . "/"; A variable used to help RT construct URLs that point back to RT. [=$WebURL] is the combination of [=$WebBaseURL] and [=$WebPath]. Generally, you shouldn't change it. $WebImagesURL = $WebURL . "/NoAuth/images/"; [=$WebImagesURL] points to the base URL where RT can find its images. If you're running the FastCGI version of the RT web interface, you should make RT's [=WebRT/html/NoAuth/images] directory available on a static web server and supply that URL as [=$WebImagesUrl] -- alternately, you can tell Apache not to run it through FastCGI. THEN Configure web server, read ManualApacheConfig ---- Prev: ManualRequirements --- Up: UserManual --- Next: ManualApacheConfig